home *** CD-ROM | disk | FTP | other *** search
/ Stone Design / Stone Design.iso / Stone_Friends / Wave / WavesWorld / Source / Libraries / tcl7.4b3 / doc / CrtPipelin.3 < prev    next >
Encoding:
Text File  |  1994-12-17  |  4.2 KB  |  102 lines
  1. '\"
  2. '\" Copyright (c) 1989-1993 The Regents of the University of California.
  3. '\" Copyright (c) 1994 Sun Microsystems, Inc.
  4. '\"
  5. '\" See the file "license.terms" for information on usage and redistribution
  6. '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
  7. '\" 
  8. '\" @(#) CrtPipelin.3 1.8 94/12/17 16:17:14
  9. '\" 
  10. .so man.macros
  11. .HS Tcl_CreatePipeline tclc
  12. .BS
  13. .SH NAME
  14. Tcl_CreatePipeline \- create one or more child processes, with I/O redirection
  15. .SH SYNOPSIS
  16. .nf
  17. \fB#include <tcl.h>\fR
  18. .sp
  19. int
  20. \fBTcl_CreatePipeline\fR(\fIinterp, argc, argv, pidArrayPtr, inPipePtr, outPipePtr, errFilePtr\fR)
  21. .SH ARGUMENTS
  22. .AS Tcl_Interp **pidArrayPtr
  23. .AP Tcl_Interp *interp in
  24. Interpreter to use for error reporting.
  25. .AP int argc in
  26. Number of strings in \fIargv\fR array.
  27. .AP char **argv in
  28. Array of strings describing command(s) and I/O redirection.
  29. .AP int **pidArrayPtr out
  30. The value at \fI*pidArrayPtr\fR is modified to hold a pointer to
  31. an array of process identifiers.  The array is dynamically
  32. allocated and must be freed by the caller.
  33. .AP int *inPipePtr out
  34. If this argument is NULL then standard input for the first command
  35. in the pipeline comes from the current standard input.
  36. If \fIinPipePtr\fR is not NULL then \fBTcl_CreatePipeline\fR will
  37. create a pipe, arrange for it to be used for standard input
  38. to the first command,
  39. and store a file id for writing to that pipe at \fI*inPipePtr\fR.
  40. If the command specified its own input using redirection, then
  41. no pipe is created and -1 is stored at \fI*inPipePtr\fR.
  42. .AP int *outPipePtr out
  43. If this argument is NULL then standard output for the last command
  44. in the pipeline goes to the current standard output.
  45. If \fIoutPipePtr\fR is not NULL then \fBTcl_CreatePipeline\fR will
  46. create a pipe, arrange for it to be used for standard output from
  47. the last command, and store a file id for reading from that
  48. pipe at \fI*outPipePtr\fR.
  49. If the command specified its own output using redirection then
  50. no pipe is created and -1 is stored at \fI*outPipePtr\fR.
  51. .AP int *errFilePtr out
  52. If this argument is NULL then error output for all the commands
  53. in the pipeline will go to the current standard error file.
  54. If \fIerrFilePtr\fR is not NULL, error output from all the commands
  55. in the pipeline will go to a temporary file created by
  56. \fBTcl_CreatePipeline\fR.
  57. A file id to read from that file will be stored at \fI*errFilePtr\fR.
  58. The file will already have been removed, so closing the file
  59. descriptor at \fI*errFilePtr\fR will cause the file to be flushed
  60. completely.
  61. .BE
  62.  
  63. .SH DESCRIPTION
  64. .PP
  65. \fBTcl_CreatePipeline\fR processes the \fIargv\fR array and sets
  66. up one or more child processes in a pipeline configuration.
  67. \fBTcl_CreatePipeline\fR handles pipes specified with ``|'',
  68. input redirection specified with ``<'' or ``<<'', and output
  69. redirection specified with ``>'';  see the documentation for
  70. the \fBexec\fR command for details on these specifications.
  71. The return value from \fBTcl_CreatePipeline\fR is a count of
  72. the number of child processes created;  the process identifiers
  73. for those processes are stored in a \fImalloc\fR-ed array and
  74. a pointer to that array is stored at \fI*pidArrayPtr\fR.
  75. It is the caller's responsibility to free the array when finished
  76. with it.
  77. .PP
  78. If the \fIinPipePtr\fR, \fIoutPipePtr\fR, and \fIerrFilePtr\fR
  79. arguments are NULL then the pipeline's standard input, standard
  80. output, and standard error are taken from the corresponding
  81. streams of the process.  Non-NULL values may be specified for
  82. these arguments to use pipes for standard input and standard
  83. output and a file for standard error.  \fBTcl_CreatePipeline\fR
  84. will create the requested pipes or file and return file identifiers
  85. that may be used to read or write them.  It is the caller's
  86. responsibility to close all of these files when they are no
  87. longer needed.  If \fIargv\fR specifies redirection for standard
  88. input or standard output, then pipes will not be created even
  89. if requested by the \fIinPipePtr\fR and \fIoutPipePtr\fR
  90. arguments.
  91. .PP
  92. If an error occurs in \fBTcl_CreatePipeline\fR (e.g. ``|'' or
  93. ``<'' was the last argument in \fIargv\fR, or it wasn't possible
  94. to fork off a child), then -1 is returned
  95. and \fIinterp->result\fR is set to an error message.
  96.  
  97. .SH "SEE ALSO"
  98. \fBTcl_DetachPids\fR, \fBTcl_ReapDetachedProcs\fR
  99.  
  100. .SH KEYWORDS
  101. background, child, detach, fork, process, status, wait
  102.